<html>
  <head>
    <meta content="text/html; charset=UTF-8" http-equiv="content-type">
    <title>Okapi Libraries ReadMe</title>
    <style type="text/css">body { font-family: Arial, Helvetica, sans-serif; }
      table { border-collapse: collapse; }
      table, th, td { border: 1px solid black; padding: 5px;}
    </style>
  </head>
  <body>
    <h1>Release Notes - Okapi XLIFF Toolkit @version@, @date@</h1>
    <ul>
      <li><a href="#overview">Overview</a></li>
      <li><a href="#setup">Requirements and Installation</a></li>
      <li><a href="#documentation">Documentation</a></li>
      <li><a href="#support">Support</a></li>
      <li><a href="#validation">Validation</a></li>
      <li><a href="#prefixes">Prefixes for Fragment Identifiers</a></li>
      <li><a href="#its">ITS Support</a></li>
    </ul>
    <hr>
    <h2><a name="overview"></a>Overview</h2>
    <p>This package provides a library that implements the XLIFF 2.0 OASIS
      Standard.</p>
    This library is under LGPL license and the source code for this package is
    hosted in the <a href="http://code.google.com/p/okapi-xliff-toolkit/source/browse/">Okapi
      XLIFF Toolkit project</a>.
    <p>This distribution includes:</p>
    <ul>
      <li><code>okapi-lib-xliff2-&lt;version&gt;.jar</code> - Java library that
        includes an XLIFF reader class, an XLIFF writer class, and various
        helper classes to manipulate XLIFF data.</li>
      <ul>
        <li>This library has no dependency. This is the only file you need if
          you are using the library with your own application.</li>
        <li>You can also get this JAR from the project's Maven repository at <a

            target="_blank" href="http://repository-okapi-xliff.forge.cloudbees.com/release/">http://repository-okapi-xliff.forge.cloudbees.com/release/</a>.
          <br>
          &nbsp;</li>
      </ul>
      <li><code>lynx.jar</code> - A tool to test and perform various
        manipulation of XLIFF documents.</li>
      <li><code>lynx.bat</code> - A batch file to run Lynx (for Windows).</li>
      <li><code>lynxPrompt.bat</code> - An helper batch file used by
        startLynxPrompt (for Windows).</li>
      <li><code>startLynxPrompt.bat</code> - A Windows batch file to start a DOS
        prompt where you can call Lynx from any folder.</li>
      <li><code>lynx.sh</code> - A Bash shell script to run Lynx (on Linux and
        Macintosh).</li>
    </ul>
    <h3>Lynx</h3>
    <p>Lynx is a command-line tools that can performs validation and a few other
      tasks on XLIFF 2 documents.<br>
      It also implements short examples of code that illustrate specific aspects
      of the library and demonstrate conformance (See <a href="conformance/conformance-notes.html">conformance-notes.html</a>
      for details).</p>
    When started without parameters, Lynx opens a dialog box where you can
    validate a document.
    <p>Note that you can also perform validation on-line here: <a target="_blank"

        href="http://okapi-lynx.appspot.com/validation">http://okapi-lynx.appspot.com/validation</a>.</p>
    <p><b>In Windows, to start a DOS prompt from where you can call Lynx, just
        double-click on <code>startLynxPrompt.bat</code></b></p>
    <ul>
      <li>The command <code>-v</code> validates the XLIFF document against the
        XLIFF 2 schemas and performs the processing validation.</li>
      <li>The command <code>-r</code> reads the XLIFF document and display the
        parsed components.</li>
      <li>The command <code>-rw</code> reads the XLIFF document and re-write
        it.</li>
      <ul>
        <li>The option <code>-rd</code> removes the original data of the inline
          codes.</li>
        <li>The option <code>-ra</code> removes the inline annotation markers (<code>&lt;mrk&gt;</code>/<code>&lt;sm&gt;</code>/<code>&lt;em&gt;</code>).</li>
        <li>The option <code>-rx</code> removes the extension elements and
          attributes (not touching the skeleton content).</li>
        <li>The option <code>-rm &lt;nsSuffix&gt;</code> removes all elements
          and attributes for the module ending with <code>&lt;nsSuffix&gt;</code>.
          Use <code>-rm all</code> to remove all modules.</li>
        <li>The option <code>-pseudo</code> creates basic pseudo-translations
          from the source (existing translations are overwritten). The
          transformation is done as follow: digits are replaced by 'N', Ctrl+A
          by 'A', the letters 'A' and 'a' by a Ctrl+A, other letters by 'Z'.</li>
        <li>The option <code>-join1</code> removes all segmentation breaks in
          each unit (except the segments with <code>canResegment='no'</code>
          (Modifier mode)).</li>
        <li>The option <code>-join2</code> removes all segmentation breaks in
          each unit (even the segments with <code>canResegment='no'</code>
          (Merger mode)).</li>
        <li>The option <code>-seg</code> applies basic re-segmentation to each
          existing segment (breaks after the sequence period + whitespace). To
          re-segment a unit already segmented use <code>-join1</code> and <code>-seg</code>
          at the same time.</li>
      </ul>
      <li>The command <code>-fr</code> finds a reference in the input file.</li>
      <ul>
        <li>The option <code>-prefixes path</code> allows the user to provide
          the path of a properties file with additional prefixes for URI
          fragment identification.</li>
      </ul>
      <li>The command <code>-vr</code> verifies the syntax of the <code>ref</code>
        attributes in the annotations of in the input file.</li>
      <ul>
        <li>The option <code>-prefixes path</code> allows the user to provide
          the path of a properties file with additional prefixes for URI
          fragment identification.</li>
      </ul>
      <li>The command <code>-lp</code> lists all extensions/modules prefixes
        allowed in fragment identifiers.</li>
      <ul>
        <li>The option <code>-prefixes path</code> allows the user to provide
          the path of a properties file with additional prefixes for URI
          fragment identification. </li>
      </ul>
      <li>The command <code>-pvr</code> processes the validation rules of any <code>&lt;validation&gt;</code>
        element found in the document.</li>
      <ul>
        <li>The option <code>-prefixes path</code> allows the user to provide
          the path of a properties file with additional prefixes for URI
          fragment identification. </li>
      </ul>
      <li>The command <code>-html</code> reads the XLIFF document and creates
        an HTML simple output from it.</li>
      <li>The command <code>-its datacat</code> creates a test output of the
        input file for the given data category. the values for the parameter are
        the same as the data category identifiers used for the <code>annotatorsRef</code>
        attribute (See <a href="http://www.w3.org/TR/its20/#datacategories-overview">http://www.w3.org/TR/its20/#datacategories-overview</a>).</li>
      <li>The command <code>-x</code> lists all examples available.</li>
      <li>The command <code>-x&lt;N&gt;</code> (where <code>&lt;N&gt;</code>
        is a number) outputs the example of the snippet with that number. Use <code>-source</code>
        to show the corresponding source code.</li>
      <li>The option <code>-trace</code> enable the display of the exception
        stack when an error occurs.</li>
      <li>Calling the application without parameter opens a dialog box from
        where you can select (or drag and drop) a document and validate it.</li>
    </ul>
    <p>For example (assuming Windows command-line and the distribution
      directory):</p>
    <ul>
      <li>To validate a document, type:</li>
    </ul>
    <blockquote>
      <pre>lynx samples/example.html.xlf</pre>
    </blockquote>
    <ul>
      <li>To segment and pseudo translate a document, type:</li>
    </ul>
    <blockquote>
      <pre>lynx -rw -seg -pseudo samples/example.html.xlf</pre>
    </blockquote>
    <ul>
      <li>To execute the example 6 and display its source code, type:</li>
    </ul>
    <blockquote>
      <pre>lynx -x6 -source</pre>
    </blockquote>
    <ul>
      <li>To remove all extensions as well as the Format Style module from a
        document, type:</li>
    </ul>
    <blockquote>
      <pre>lynx -rw -rx -rm "fs:2.0" myFile.xlf</pre>
    </blockquote>
    <ul>
      <li>To display the parsed parts of&nbsp; the <code>hello.html.xlf</code>
        document, type:</li>
    </ul>
    <blockquote>
      <pre>lynx -r samples/hello.html.xlf</pre>
    </blockquote>
    <ul>
      <li>To find the element corresponding to the reference <code>"#f=f1/u=tu1"</code>
        (i.e. the unit with id=tu1 in the file id=f1), type:</li>
    </ul>
    <blockquote>
      <pre>lynx -fr #f=f1/u=tu1 samples/hello.html.xlf</pre>
    </blockquote>
    <ul>
      <li>To get a complete list of the tool's command and options, type:</li>
    </ul>
    <blockquote>
      <pre>lynx -?</pre>
    </blockquote>
    <hr>
    <h2><a name="setup"></a>Requirements and Installation</h2>
    <h3>Requirements</h3>
    <ul>
      <li>Java 1.7 or later.</li>
    </ul>
    <h3>Installation</h3>
    <p>To install the library:</p>
    <ol>
      <li>Simply unzip the distribution in the directory where you want to use
        it.</li>
    </ol>
    <h3>Uninstallation</h3>
    <p>To uninstall the library:</p>
    <ol>
      <li>Simply delete the jar file from your directory.</li>
    </ol>
    <hr>
    <h2><a name="documentation"></a>Documentation</h2>
    <p>The documentation of the library is available <a href="documentation/index.html">in
        the documentation sub-directory</a>.</p>
    <p>See also <a href="https://code.google.com/p/okapi-xliff-toolkit/wiki/Getting_Started">the
        online Getting Started guide</a>.</p>
    <hr>
    <h2><a name="support"></a>Support</h2>
    <p>If you have questions, suggestions or bug to report, you can do this
      different ways:</p>
    <ul>
      <li>To read more about XLIFF and provide feedback or ask questions
        regarding the format, use one of the XLIFF mailing lists:
        <ul>
          <li><a href="http://lists.oasis-open.org/archives/xliff/">http://lists.oasis-open.org/archives/xliff/</a>
            (anyone can read, only XLIFF TC members can post).</li>
          <li><a href="http://lists.oasis-open.org/archives/xliff-comment/">http://lists.oasis-open.org/archives/xliff-comment/</a>
            (anyone can read, anyone can register to post).</li>
          <li><a href="http://lists.oasis-open.org/archives/xliff-users/">http://lists.oasis-open.org/archives/xliff-users/</a>
            (anyone can read, anyone can register to post).</li>
        </ul>
      </li>
      <li>To get the source code, and post bug reports or request for
        enhancement, use the <a href="http://code.google.com/p/okapi-xliff-toolkit/">Google
          Code project site</a>.</li>
      <li>To get help with the tool or discuss it in general, use the <a target="_blank"

          href="http://tech.groups.yahoo.com/group/okapitools/">Okapi Tools
          users group</a> (anyone can read, anyone can register to post).</li>
    </ul>
    <hr>
    <h2><a name="validation"></a>Validation</h2>
    <p>Important notes on what validation the library performs:</p>
    <ul>
      <li>The content of non-implemented modules and extensions are not
        validated beyond the schema validation.<br>
        (For example the XLIFF elements in the Change Tracking module <code>&lt;revision&gt;</code>
        elements are only validated against the schema, not for processing
        requirements or constraints not enforced in the schema). This is because
        as far as the library is concerned they are part of the extension
        elements.</li>
      <li>The <em>validation</em> done is about whether or not the document is
        valid, not about processing the rules of the Validation module. Such
        validation can be done in addition using the library API or the command
        <code>-pvr</code> with Lynx. </li>
    </ul>
    <hr>
    <h2><a name="prefixes"></a>Prefixes for Fragment Identifiers</h2>
    <p>The list of prefixes allowed in fragment identifiers is stored in the <code>
        prefixes.properties</code> file in the JAR file of the library.</p>
    <p>See the <a href="https://wiki.oasis-open.org/xliff/FragIDPrefixRegistration">Fragment
        Identifier Registration page</a> for details and the list of all
      registered prefixes. </p>
    <p>The option <code>-prefixes path</code> allows the user to provide the
      path of a properties file with additional prefixes for URI fragment
      identification. Those custom prefixes are added to the default ones. Note
      that you can have more than one namespace associated to a single prefix.</p>
    <p>The format of the custom prefixes file is the same as the default one:</p>
    <ul>
      <li>Java properties file format as described in <a href="http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load%28java.io.Reader%29">http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load(java.io.Reader)</a></li>
      <li>each entry is in the form: <code>&lt;namespace-uri&gt;=&lt;prefix&gt;</code></li>
      <li>One entry per line.</li>
      <li>Comment lines have a character&nbsp;<code>'#'</code> or <code>'!'</code>
        as the first non-white space character.</li>
      <li>Do not forget to escape literal characters such as <code>':'</code>,
        <code>'='</code>, or <code>'\'</code> in the URI. See the Java
        documentation for the full list.</li>
    </ul>
    <p>To modify the default <code>prefixes.properties</code> file in the
      library JAR file:</p>
    <ul>
      <li>Extract the properties file from the JAR file.</li>
      <li>Add or remove the pairs.</li>
      <li>Add the modified properties file in the JAR, overriding the existing
        one.</li>
    </ul>
    <hr>
    <h2><a name="its"></a>ITS Support</h2>
    <p>As of this release of the toolkit, an effort to map and create a module
      for the Internationalization Tag Set 2.0 is in progress.</p>
    <ul>
      <li>ITS 2.0 Specification: <a href="http://www.w3.org/TR/its20/">http://www.w3.org/TR/its20</a></li>
      <li>XLIFF 2 and ITS 2.0 mapping page: <a target="_blank" href="http://www.w3.org/International/its/wiki/XLIFF_2.0_Mapping">http://www.w3.org/International/its/wiki/XLIFF_2.0_Mapping</a></li>
    </ul>
    <p>Some data categories are directly mapped to existing XLIFF 2.0 features,
      others are mapped through the ITS Module.</p>
    <p>See the documentation for <a href="http://okapi.opentag.com/xlifflib/javadoc/net/sf/okapi/lib/xliff2/its/IWithITSAttributes.html">IWithITSAttributes</a>
      and <a href="http://okapi.opentag.com/xlifflib/javadoc/net/sf/okapi/lib/xliff2/its/IWithITSGroups.html">IWithITSGroups</a>
      for details.</p>
    <ul>
    </ul>
    <h3>Translate</h3>
    <ul>
    </ul>
    <table>
      <tbody>
        <tr>
          <td>Location</td>
          <td>Access</td>
        </tr>
        <tr>
          <td>&lt;file&gt;</td>
          <td>StartFileData.getTranslate()</td>
        </tr>
        <tr>
          <td>&lt;group&gt;</td>
          <td>StartGroupData.getTranslate()</td>
        </tr>
        <tr>
          <td>&lt;unit&gt;</td>
          <td>Unit.getTranslate()</td>
        </tr>
        <tr>
          <td>&lt;mrk&gt; and &lt;sm/&gt;</td>
          <td>MTag.getTranslate()</td>
        </tr>
      </tbody>
    </table>
    <h3>Domain</h3>
    <table border="1">
      <tbody>
        <tr>
          <td>Location</td>
          <td>Access</td>
        </tr>
        <tr>
          <td>&lt;group&gt;<br>
          </td>
          <td>StartGroupData.getITSItems().get(DataCategories.DOMAIN)<br>
          </td>
        </tr>
        <tr>
          <td>&lt;unit&gt;</td>
          <td>Unit.getITSItems().get(DataCategories.DOMAIN)</td>
        </tr>
        <tr>
          <td>&lt;mrk&gt; and &lt;sm/&gt;</td>
          <td>MTag.getITSItems().get(DataCategories.DOMAIN)</td>
        </tr>
      </tbody>
    </table>
    <ul>
    </ul>
    <h3>MT Confidence</h3>
    <table border="1">
      <tbody>
        <tr>
          <td>Location</td>
          <td>Access</td>
        </tr>
        <tr>
          <td>&lt;mrk&gt; and &lt;sm/&gt;</td>
          <td>MTag.getITSItems().get(DataCategories.MTCONFIDENCE)</td>
        </tr>
        <tr>
          <td>&lt;mtc:match matchQuality&gt;</td>
          <td>Not implemented</td>
        </tr>
      </tbody>
    </table>
    <ul>
    </ul>
    <h3>Terminology</h3>
    <p>TODO</p>
    <h3>Text Analysis</h3>
    <p>TODO</p>
    <h3>Provenance</h3>
    <p>TODO (with some restrictions currently)</p>
    <h3>Localization Quality Issue</h3>
    <p>TODO (with some restriction currently)</p>
    <h3>Allowed Characters</h3>
    <p>TODO</p>
    <h3> </h3>
  </body>
</html>
